What is postcss-image-set-function?
The postcss-image-set-function package is a PostCSS plugin that allows you to polyfill the CSS image-set function. This function is used to specify different images to use in different situations, such as high-resolution displays or different types of devices. The plugin transforms image-set notation into a background-image declaration that is compatible with all browsers.
What are postcss-image-set-function's main functionalities?
Transform image-set function
This feature allows you to write CSS using the image-set function, which the plugin will then transform into a background-image property with corresponding -webkit-image-set for compatibility with browsers that support it.
background-image: image-set('img/test.png' 1x, 'img/test-2x.png' 2x, 'img/test-print.png' 600dpi);
Fallback for browsers without image-set support
The plugin provides a fallback for browsers that do not support the image-set function by outputting a standard background-image property with the 1x image as the default.
background-image: url('img/test.png');
background-image: image-set('img/test.png' 1x, 'img/test-2x.png' 2x);
Other packages similar to postcss-image-set-function
postcss-preset-env
postcss-preset-env is a plugin that allows you to use future CSS features today. It includes polyfills for various CSS features, including the image-set function, similar to postcss-image-set-function, but it is more comprehensive as it covers a wide range of CSS features.
postcss-assets
postcss-assets is a PostCSS plugin that helps manage project assets. It can resolve paths, inline files, and more. While it does not directly polyfill the image-set function, it can be used in conjunction with other plugins to manage images and resolutions, which is a part of what postcss-image-set-function does.
PostCSS image-set() Function
PostCSS image-set() Function lets you display resolution-dependent images
using the image-set()
function in CSS, following the CSS Images
specification.
.example {
background-image: image-set(
url(img.png) 1x,
url(img@2x.png) 2x,
url(img@print.png) 600dpi
);
}
/* becomes */
.example {
background-image: url(img.png);
}
@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
.example {
background-image: url(img@2x.png);
}
}
@media (-webkit-min-device-pixel-ratio: 6.25), (min-resolution: 600dpi) {
.example {
background-image: url(my@print.png);
}
}
.example {
background-image: image-set(
url(img.png) 1x,
url(img@2x.png) 2x,
url(img@print.png) 600dpi
);
}
Usage
Add PostCSS image-set() Function to your project:
npm install postcss-image-set-function --save-dev
Use PostCSS image-set() Function as a PostCSS plugin:
const postcss = require('postcss');
const postcssImageSetFunction = require('postcss-image-set-function');
postcss([
postcssImageSetFunction()
]).process(YOUR_CSS );
PostCSS image-set() Function runs in all Node environments, with special
instructions for:
Options
preserve
The preserve
option determines whether the original declaration using
image-set()
is preserved. By default, it is preserved.
postcssImageSetFunction({ preserve: false })
.example {
background-image: image-set(
url(img.png) 1x,
url(img@2x.png) 2x,
url(img@print.png) 600dpi
);
}
/* becomes */
@media (-webkit-min-device-pixel-ratio: 1), (min-resolution: 96dpi) {
.example {
background-image: url(img.png);
}
}
@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
.example {
background-image: url(img@2x.png);
}
}
@media (-webkit-min-device-pixel-ratio: 6.25), (min-resolution: 600dpi) {
.example {
background-image: url(my@print.png);
}
}
onInvalid
The onInvalid
option determines how invalid usage of image-set()
should be
handled. By default, invalid usages of image-set()
are ignored.
They can be configured to emit a warning with warn
or throw an exception with throw
.
postcssImageSetFunction({ onInvalid: 'warn' })
postcssImageSetFunction({ onInvalid: 'throw' })
Image Resolution
The image-set()
function allows an author to provide multiple resolutions of
an image and let the browser decide which is most appropriate in a given
situation. The image-set()
also never fails to choose an image; the
<resolution>
just helps determine which of the images is chosen.
Since this plugin is not a browser, the image options are sorted by device
pixel ratio and the lowest ratio is used as the default, while the remaining
images are pushed behind media queries.
Therefore, this plugin can only approximate native browser behavior. While
images should typically match the resolution as the device they’re being viewed
in, other factors can affect the chosen image. For example, if the user is on a
slow mobile connection, the browser may prefer to select a lower-res image
rather than wait for a larger, resolution-matching image to load.